{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _nb_callback:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Callback"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `Callback` class can be used to receive a notification of the algorithm object each generation.\n",
    "This can be useful to keep track of metrics, do additional calculations or even modify the algorithm object during the run.\n",
    "The latter is only recommend for experienced users.\n",
    "\n",
    "For instance, to keep track of the best solution each generation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "code": "algorithms/usage_callback.py"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "=============================================\n",
      "n_gen |  n_eval |     fopt     |     favg    \n",
      "=============================================\n",
      "    1 |     100 |  0.387099336 |  0.831497479\n",
      "    2 |     200 |  0.302189349 |  0.578035582\n",
      "    3 |     300 |  0.267733594 |  0.443801185\n",
      "    4 |     400 |  0.188215259 |  0.347200983\n",
      "    5 |     500 |  0.083479177 |  0.272644726\n",
      "    6 |     600 |  0.083479177 |  0.212567874\n",
      "    7 |     700 |  0.072492126 |  0.173574163\n",
      "    8 |     800 |  0.051256476 |  0.140740462\n",
      "    9 |     900 |  0.041778020 |  0.110370322\n",
      "   10 |    1000 |  0.041778020 |  0.089125798\n",
      "   11 |    1100 |  0.031644566 |  0.071339910\n",
      "   12 |    1200 |  0.030055810 |  0.057941249\n",
      "   13 |    1300 |  0.021855327 |  0.047786695\n",
      "   14 |    1400 |  0.017620999 |  0.040676540\n",
      "   15 |    1500 |  0.014756395 |  0.034902705\n",
      "   16 |    1600 |  0.014756395 |  0.029778240\n",
      "   17 |    1700 |  0.012976416 |  0.026185115\n",
      "   18 |    1800 |  0.008637920 |  0.022664820\n",
      "   19 |    1900 |  0.006399439 |  0.019648350\n",
      "   20 |    2000 |  0.006399439 |  0.016725603\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "image/png": {
       "height": 248,
       "width": 378
      },
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "from pymoo.algorithms.so_genetic_algorithm import GA\n",
    "from pymoo.factory import get_problem\n",
    "from pymoo.model.callback import Callback\n",
    "from pymoo.optimize import minimize\n",
    "\n",
    "\n",
    "class MyCallback(Callback):\n",
    "\n",
    "    def __init__(self) -> None:\n",
    "        super().__init__()\n",
    "        self.data[\"best\"] = []\n",
    "\n",
    "    def notify(self, algorithm):\n",
    "        self.data[\"best\"].append(algorithm.pop.get(\"F\").min())\n",
    "\n",
    "\n",
    "problem = get_problem(\"sphere\")\n",
    "\n",
    "algorithm = GA(pop_size=100)\n",
    "\n",
    "res = minimize(problem,\n",
    "               algorithm,\n",
    "               ('n_gen', 20),\n",
    "               seed=1,\n",
    "               callback=MyCallback(),\n",
    "               save_history=True,\n",
    "               verbose=True)\n",
    "\n",
    "val = res.algorithm.callback.data[\"best\"]\n",
    "plt.plot(np.arange(len(val)), val)\n",
    "plt.show()\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the analysis of the run should be done during post-processing the option `save_history` can be used as well. If a callback is used the history does not need to be saved.\n",
    "By using the history object the same as above can be achieved by using the stored information during the run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "image/png": {
       "height": 248,
       "width": 378
      },
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "val = [e.pop.get(\"F\").min() for e in res.history]\n",
    "plt.plot(np.arange(len(val)), val)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the `save_history` is true a deep copy of the algorithm object takes place each generation. Please note that this can be quite expensive and might not be desired for all runs. However, it provides great post-processing options because all data can be accessed respectively."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
